<%
title = 'http'
description = 'The HTTP protocol support by mountebank'
%>

<% include ../../_header %>

<h1>http</h1>

<h2>Imposter Creation Parameters</h2>

<table>
  <tr>
    <th>Parameter</th>
    <th>Options</th>
    <th>Required?</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>protocol</code></td>
    <td><code>http</code></td>
    <td>Yes</td>
    <td>N/A</td>
    <td>&nbsp;</td>
  </tr>
  <tr>
    <td><code>port</code></td>
    <td>Any valid port number</td>
    <td>No</td>
    <td>A randomly assigned port.  mountebank will return the actual value
    in the <code>POST</code> response.</td>
    <td>The port to run the imposter on.</td>
  </tr>
  <tr>
    <td><code>name</code></td>
    <td>Any string</td>
    <td>No</td>
    <td>empty string</td>
    <td>Included in the logs, useful when multiple imposters are set up.</td>
  </tr>
  <tr>
    <td><code>recordRequests</code></td>
    <td><code>true</code> or <code>false</code></td>
    <td>No</td>
    <td>false</td>
    <td>Adds <a href='/docs/api/mocks'>mock verification</a> support by remembering the requests
        made to this imposter.  Note that this represents a memory leak for any long running
        <code>mb</code> process, as requests are never forgotten.</td>
  </tr>
  <tr>
    <td><code>stubs</code></td>
    <td>Valid stubs</td>
    <td>No</td>
    <td>An empty array</td>
    <td>The list of stubs responsible for matching a request and returning a response</td>
  </tr>
  <tr>
    <td><code>defaultResponse</code></td>
    <td>A valid response, see below for response fields</td>
    <td>No</td>
    <td><pre><code>
{
  "statusCode": 200,
  "headers": {
    "connection": "close"
   },
  "body": ""
}
    </code></pre></td>
    <td>The default response to send if no predicate matches. Also represents the default values
        that get merged into a response that doesn't specify every field</td>
  </tr>
  <tr>
    <td><code>allowCORS</code></td>
    <td>boolean</td>
    <td>No</td>
    <td>false</td>
    <td>If true, mountebank will allow all CORS preflight requests on the imposter.</td>
  </tr>
</table>

<p>http and https imposters prevent keepalive connections by default because they can lead
to some difficult to troubleshoot problems in use cases where you start in stop imposters
in the scope of one test.  The test may shut down the imposter, which prevents new connections
for the port, but that won't prevent the system under test from trying to reuse an existing
keepalive socket. If you need to override that behavior, override the <code>defaultResponse</code>
field and explicitly set the <code>Connection</code> header to <code>keep-alive</code>.</p>

<h2>HTTP Requests</h2>

<table>
  <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
  </tr>
  <tr>
    <td><code>requestFrom</code></td>
    <td>The client socket, primarily used for logging and debugging.</td>
    <td>string</td>
  </tr>
  <tr>
      <td><code>path</code></td>
      <td>The path of the request, without the querystring</td>
      <td>string</td>
  </tr>
  <tr>
      <td><code>query</code></td>
      <td>The querystring of the request</td>
      <td>object</td>
  </tr>
  <tr>
      <td><code>method</code></td>
      <td>The request method</td>
      <td>string</td>
  </tr>
  <tr>
      <td><code>headers</code></td>
      <td>The HTTP headers</td>
      <td>object</td>
  </tr>
  <tr>
      <td><code>body</code></td>
      <td>The request body</td>
      <td>string</td>
  </tr>
  <tr>
      <td><code>form</code></td>
      <td>Form-encoded key-value pairs in the body. Supports key-specific predicates. For example,
        with a body of <code>firstname=bob&lastname=smith</code>, you could set a predicate on
        just <code>lastname</code>.</td>
      <td>object</td>
  </tr>
</table>

<h2>HTTP Responses</h2>

<table>
  <tr>
    <th>Field</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td><code>statusCode</code></td>
    <td>int</td>
    <td><code>200</code></td>
  </tr>
  <tr>
    <td><code>headers</code></td>
    <td>object</td>
    <td><code>{ "Connection": "close" }</code></td>
  </tr>
  <tr>
    <td><code>body</code></td>
    <td>string or object</td>
    <td><code>""</code></td>
  </tr>
  <tr>
    <td><code>_mode</code></td>
    <td>string - <code>binary</code> or <code>text</code></td>
    <td><code>text</code></td>
  </tr>
</table>

<p>While HTTP bodies are strings, you can pass a JSON body in the API.  That will be
turned into a valid JSON string when the response is sent.</p>

<p>HTTP bodies will always be recorded as text, but mountebank does have the ability
to respond in binary.  If you want to set up a canned binary response, set the <code>_mode</code>
to <code>binary</code> and base64 encode the <code>body</code>.  mountebank will also try
to preserve binary responses in proxies by looking at the <code>Content-Encoding</code> and
<code>Content-Type</code> headers.</p>

<h2 id='inline-json-response-bodies'>Inline JSON For Response Bodies</h2>

<p>The example below shows passing an inline JSON object as the response body.</p>

<testScenario name='json-example'>
    <step type='http'>
<pre><code>POST /imposters HTTP/1.1
Host: localhost:<%= port %>
Accept: application/json
Content-Type: application/json

{
  "port": 4545,
  "protocol": "http",
  "stubs": [
    {
      "responses": [
        {
          "is": {
            "statusCode": 200,
            "headers": {
              "Content-Type": "application/json"
            },
            "body": {
              "bikeId": 123,
              "name": "Turbo Bike 4000"
            }
          }
        }
      ]
    }
  ]
}</code></pre>
    </step>

<p>Now let's test the response by calling the imposter:</p>

    <step type='http'>
<pre><code>GET / HTTP/1.1
Host: localhost:4545
Accept: application/json</code></pre>

        <assertResponse>
<pre><code>HTTP/1.1 200 OK
Content-Type: application/json
Connection: close
Date: <volatile>Sun, 15 Nov 2015 01:02:03 GMT</volatile>
Transfer-Encoding: chunked

{
  "bikeId": 123,
  "name": "Turbo Bike 4000"
}</code></pre>
        </assertResponse>
    </step>

    <step type='http'>
<code class='hidden'>DELETE /imposters/4545 HTTP/1.1
Host: localhost:<%= port %></code>
    </step>
</testScenario>

<% include ../../_footer %>
